<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        
        <title>
            
    
                Core Events
             &mdash; 
    SQLAlchemy 0.8 Documentation

        </title>
        
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/docs.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '../',
          VERSION:     '0.8.2',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/init.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
        <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
        <link rel="up" title="SQLAlchemy Core" href="index.html" />
        <link rel="next" title="Custom SQL Constructs and Compilation Extension" href="compiler.html" />
        <link rel="prev" title="Events" href="event.html" />

    </head>
    <body>
        










<div id="docs-container">



<div id="docs-header">
    <h1>SQLAlchemy 0.8 Documentation</h1>

    <div id="docs-search">
    Search:
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>

    <div id="docs-version-header">
        Release: <span class="version-num">0.8.2</span> | Release Date: July 3, 2013


    </div>

</div>

<div id="docs-top-navigation">
    <div id="docs-top-page-control" class="docs-navigation-links">
        <ul>
            <li>Prev:
            <a href="event.html" title="previous chapter">Events</a>
            </li>
            <li>Next:
            <a href="compiler.html" title="next chapter">Custom SQL Constructs and Compilation Extension</a>
            </li>

        <li>
            <a href="../contents.html">Table of Contents</a> |
            <a href="../genindex.html">Index</a>
            | <a href="../_sources/core/events.txt">view source
        </li>
        </ul>
    </div>

    <div id="docs-navigation-banner">
        <a href="../index.html">SQLAlchemy 0.8 Documentation</a>
                » <a href="index.html" title="SQLAlchemy Core">SQLAlchemy Core</a>
        » 
                Core Events
             

        <h2>
            
                Core Events
            
        </h2>
    </div>

</div>

<div id="docs-body-container">

    <div id="docs-sidebar">
    <h3><a href="../index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">Core Events</a><ul>
<li><a class="reference internal" href="#connection-pool-events">Connection Pool Events</a></li>
<li><a class="reference internal" href="#sql-execution-and-connection-events">SQL Execution and Connection Events</a></li>
<li><a class="reference internal" href="#schema-events">Schema Events</a></li>
</ul>
</li>
</ul>


    <h4>Previous Topic</h4>
    <p>
    <a href="event.html" title="previous chapter">Events</a>
    </p>
    <h4>Next Topic</h4>
    <p>
    <a href="compiler.html" title="next chapter">Custom SQL Constructs and Compilation Extension</a>
    </p>


    <h4>Quick Search</h4>
    <p>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </p>

    </div>

    <div id="docs-body" class="withsidebar" >
        
<div class="section" id="core-events">
<span id="core-event-toplevel"></span><h1>Core Events<a class="headerlink" href="#core-events" title="Permalink to this headline">¶</a></h1>
<p>This section describes the event interfaces provided in
SQLAlchemy Core.
For an introduction to the event listening API, see <a class="reference internal" href="event.html"><em>Events</em></a>.
ORM events are described in <a class="reference internal" href="../orm/events.html"><em>ORM Events</em></a>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.7: </span>The event system supercedes the previous system of &#8220;extension&#8221;, &#8220;listener&#8221;,
and &#8220;proxy&#8221; classes.</p>
<div class="section" id="connection-pool-events">
<h2>Connection Pool Events<a class="headerlink" href="#connection-pool-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.PoolEvents">
<em class="property">class </em><tt class="descclassname">sqlalchemy.events.</tt><tt class="descname">PoolEvents</tt><a class="headerlink" href="#sqlalchemy.events.PoolEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Available events for <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a>.</p>
<p>The methods here define the name of an event as well
as the names of members that are passed to listener
functions.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>

<span class="k">def</span> <span class="nf">my_on_checkout</span><span class="p">(</span><span class="n">dbapi_conn</span><span class="p">,</span> <span class="n">connection_rec</span><span class="p">,</span> <span class="n">connection_proxy</span><span class="p">):</span>
    <span class="s">&quot;handle an on checkout event&quot;</span>

<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">Pool</span><span class="p">,</span> <span class="s">&#39;checkout&#39;</span><span class="p">,</span> <span class="n">my_on_checkout</span><span class="p">)</span></pre></div>
</div>
<p>In addition to accepting the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> class and
<a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> instances, <a class="reference internal" href="#sqlalchemy.events.PoolEvents" title="sqlalchemy.events.PoolEvents"><tt class="xref py py-class docutils literal"><span class="pre">PoolEvents</span></tt></a> also accepts
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> objects and the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> class as
targets, which will be resolved to the <tt class="docutils literal"><span class="pre">.pool</span></tt> attribute of the
given engine or the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> class:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">&quot;postgresql://scott:tiger@localhost/test&quot;</span><span class="p">)</span>

<span class="c"># will associate with engine.pool</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="s">&#39;checkout&#39;</span><span class="p">,</span> <span class="n">my_on_checkout</span><span class="p">)</span></pre></div>
</div>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.checkin">
<tt class="descname">checkin</tt><big>(</big><em>dbapi_connection</em>, <em>connection_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.checkin" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection returns to the pool.</p>
<p>Note that the connection may be closed, and may be None if the
connection has been invalidated.  <tt class="docutils literal"><span class="pre">checkin</span></tt> will not be called
for detached connections.  (They do not return to the pool.)</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>dbapi_con</strong> &#8211; A raw DB-API connection</li>
<li><strong>con_record</strong> &#8211; The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.checkout">
<tt class="descname">checkout</tt><big>(</big><em>dbapi_connection</em>, <em>connection_record</em>, <em>connection_proxy</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.checkout" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection is retrieved from the Pool.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>dbapi_con</strong> &#8211; A raw DB-API connection</li>
<li><strong>con_record</strong> &#8211; The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
<li><strong>con_proxy</strong> &#8211; The <tt class="docutils literal"><span class="pre">_ConnectionFairy</span></tt> which manages the connection for the span of
the current checkout.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>If you raise a <a class="reference internal" href="exceptions.html#sqlalchemy.exc.DisconnectionError" title="sqlalchemy.exc.DisconnectionError"><tt class="xref py py-class docutils literal"><span class="pre">DisconnectionError</span></tt></a>, the current
connection will be disposed and a fresh connection retrieved.
Processing of all checkout listeners will abort and restart
using the new connection.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.connect">
<tt class="descname">connect</tt><big>(</big><em>dbapi_connection</em>, <em>connection_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called once for each new DB-API connection or Pool&#8217;s <tt class="docutils literal"><span class="pre">creator()</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>dbapi_con</strong> &#8211; A newly connected raw DB-API connection (not a SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper).</li>
<li><strong>con_record</strong> &#8211; The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.first_connect">
<tt class="descname">first_connect</tt><big>(</big><em>dbapi_connection</em>, <em>connection_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.first_connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called exactly once for the first DB-API connection.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>dbapi_con</strong> &#8211; A newly connected raw DB-API connection (not a SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper).</li>
<li><strong>con_record</strong> &#8211; The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.reset">
<tt class="descname">reset</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.reset" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before the &#8220;reset&#8221; action occurs for a pooled connection.</p>
<p>This event represents
when the <tt class="docutils literal"><span class="pre">rollback()</span></tt> method is called on the DBAPI connection
before it is returned to the pool.  The behavior of &#8220;reset&#8221; can
be controlled, including disabled, using the <tt class="docutils literal"><span class="pre">reset_on_return</span></tt>
pool argument.</p>
<p>The <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.reset()</span></tt></a> event is usually followed by the
the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.checkin" title="sqlalchemy.events.PoolEvents.checkin"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.checkin()</span></tt></a> event is called, except in those
cases where the connection is discarded immediately after reset.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>dbapi_con</strong> &#8211; A raw DB-API connection</li>
<li><strong>con_record</strong> &#8211; The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p class="versionadded">
<span class="versionmodified">New in version 0.8.</span></p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback" title="sqlalchemy.events.ConnectionEvents.rollback"><tt class="xref py py-meth docutils literal"><span class="pre">ConnectionEvents.rollback()</span></tt></a></p>
<p class="last"><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.commit" title="sqlalchemy.events.ConnectionEvents.commit"><tt class="xref py py-meth docutils literal"><span class="pre">ConnectionEvents.commit()</span></tt></a></p>
</div>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="sql-execution-and-connection-events">
<h2>SQL Execution and Connection Events<a class="headerlink" href="#sql-execution-and-connection-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.ConnectionEvents">
<em class="property">class </em><tt class="descclassname">sqlalchemy.events.</tt><tt class="descname">ConnectionEvents</tt><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Available events for <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><tt class="xref py py-class docutils literal"><span class="pre">Connectable</span></tt></a>, which includes
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> and <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>.</p>
<p>The methods here define the name of an event as well as the names of
members that are passed to listener functions.</p>
<p>An event listener can be associated with any <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><tt class="xref py py-class docutils literal"><span class="pre">Connectable</span></tt></a>
class or instance, such as an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span><span class="p">,</span> <span class="n">create_engine</span>

<span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span>
                                                <span class="n">executemany</span><span class="p">):</span>
    <span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s">&quot;Received statement: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="n">statement</span><span class="p">)</span>

<span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">&#39;postgresql://scott:tiger@localhost/test&#39;</span><span class="p">)</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="s">&quot;before_cursor_execute&quot;</span><span class="p">,</span> <span class="n">before_cursor_execute</span><span class="p">)</span></pre></div>
</div>
<p>or with a specific <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">begin</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
    <span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="s">&#39;before_cursor_execute&#39;</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span>
                                    <span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
        <span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s">&quot;Received statement: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="n">statement</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_execute()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_cursor_execute()</span></tt></a>
events can also be established with the <tt class="docutils literal"><span class="pre">retval=True</span></tt> flag, which
allows modification of the statement and parameters to be sent
to the database.  The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_cursor_execute()</span></tt></a> event is
particularly useful here to add ad-hoc string transformations, such
as comments, to all executions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.engine</span> <span class="kn">import</span> <span class="n">Engine</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>

<span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s">&quot;before_cursor_execute&quot;</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">comment_sql_calls</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span>
                                    <span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
    <span class="n">statement</span> <span class="o">=</span> <span class="n">statement</span> <span class="o">+</span> <span class="s">&quot; -- some comment&quot;</span>
    <span class="k">return</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span></pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionEvents</span></tt></a> can be established on any
combination of <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>, as well
as instances of each of those classes.  Events across all
four scopes will fire off for a given instance of
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>.  However, for performance reasons, the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object determines at instantiation time
whether or not its parent <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> has event listeners
established.   Event listeners added to the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>
class or to an instance of <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> <em>after</em> the instantiation
of a dependent <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance will usually
<em>not</em> be available on that <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance.  The newly
added listeners will instead take effect for <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>
instances created subsequent to those event listeners being
established on the parent <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> class or instance.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>retval=False</strong> &#8211; Applies to the <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_execute()</span></tt></a> and
<a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_cursor_execute()</span></tt></a> events only.  When True, the
user-defined event function must have a return value, which
is a tuple of parameters that replace the given statement
and parameters.  See those methods for a description of
specific return arguments.</td>
</tr>
</tbody>
</table>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.8: </span><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionEvents</span></tt></a> can now be associated
with any <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><tt class="xref py py-class docutils literal"><span class="pre">Connectable</span></tt></a> including <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>,
in addition to the existing support for <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>.</p>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.after_cursor_execute">
<tt class="descname">after_cursor_execute</tt><big>(</big><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>executemany</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept low-level cursor execute() events after execution.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>cursor</strong> &#8211; DBAPI cursor object.  Will have results pending
if the statement was a SELECT, but these should not be consumed
as they will be needed by the <a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a>.</li>
<li><strong>statement</strong> &#8211; string SQL statement</li>
<li><strong>parameters</strong> &#8211; Dictionary, tuple, or list of parameters being
passed to the <tt class="docutils literal"><span class="pre">execute()</span></tt> or <tt class="docutils literal"><span class="pre">executemany()</span></tt> method of the
DBAPI <tt class="docutils literal"><span class="pre">cursor</span></tt>.  In some cases may be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>context</strong> &#8211; <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> object in use.  May
be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>executemany</strong> &#8211; boolean, if <tt class="docutils literal"><span class="pre">True</span></tt>, this is an <tt class="docutils literal"><span class="pre">executemany()</span></tt>
call, if <tt class="docutils literal"><span class="pre">False</span></tt>, this is an <tt class="docutils literal"><span class="pre">execute()</span></tt> call.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.after_execute">
<tt class="descname">after_execute</tt><big>(</big><em>conn</em>, <em>clauseelement</em>, <em>multiparams</em>, <em>params</em>, <em>result</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.after_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept high level execute() events after execute.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>clauseelement</strong> &#8211; SQL expression construct, <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a>
instance, or string statement passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>.</li>
<li><strong>multiparams</strong> &#8211; Multiple parameter sets, a list of dictionaries.</li>
<li><strong>params</strong> &#8211; Single parameter set, a single dictionary.</li>
<li><strong>result</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a> generated by the execution.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.before_cursor_execute">
<tt class="descname">before_cursor_execute</tt><big>(</big><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>executemany</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept low-level cursor execute() events before execution,
receiving the string
SQL statement and DBAPI-specific parameter list to be invoked
against a cursor.</p>
<p>This event is a good choice for logging as well as late modifications
to the SQL string.  It&#8217;s less ideal for parameter modifications except
for those which are specific to a target backend.</p>
<p>This event can be optionally established with the <tt class="docutils literal"><span class="pre">retval=True</span></tt>
flag.  The <tt class="docutils literal"><span class="pre">statement</span></tt> and <tt class="docutils literal"><span class="pre">parameters</span></tt> arguments should be
returned as a two-tuple in this case:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s">&quot;before_cursor_execute&quot;</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span>
                <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
    <span class="c"># do something with statement, parameters</span>
    <span class="k">return</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span></pre></div>
</div>
<p>See the example at <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionEvents</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>cursor</strong> &#8211; DBAPI cursor object</li>
<li><strong>statement</strong> &#8211; string SQL statement</li>
<li><strong>parameters</strong> &#8211; Dictionary, tuple, or list of parameters being
passed to the <tt class="docutils literal"><span class="pre">execute()</span></tt> or <tt class="docutils literal"><span class="pre">executemany()</span></tt> method of the
DBAPI <tt class="docutils literal"><span class="pre">cursor</span></tt>.  In some cases may be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>context</strong> &#8211; <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> object in use.  May
be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>executemany</strong> &#8211; boolean, if <tt class="docutils literal"><span class="pre">True</span></tt>, this is an <tt class="docutils literal"><span class="pre">executemany()</span></tt>
call, if <tt class="docutils literal"><span class="pre">False</span></tt>, this is an <tt class="docutils literal"><span class="pre">execute()</span></tt> call.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>See also:</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_execute()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute" title="sqlalchemy.events.ConnectionEvents.after_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">after_cursor_execute()</span></tt></a></p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.before_execute">
<tt class="descname">before_execute</tt><big>(</big><em>conn</em>, <em>clauseelement</em>, <em>multiparams</em>, <em>params</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept high level execute() events, receiving uncompiled
SQL constructs and other objects prior to rendering into SQL.</p>
<p>This event is good for debugging SQL compilation issues as well
as early manipulation of the parameters being sent to the database,
as the parameter lists will be in a consistent format here.</p>
<p>This event can be optionally established with the <tt class="docutils literal"><span class="pre">retval=True</span></tt>
flag.  The <tt class="docutils literal"><span class="pre">clauseelement</span></tt>, <tt class="docutils literal"><span class="pre">multiparams</span></tt>, and <tt class="docutils literal"><span class="pre">params</span></tt>
arguments should be returned as a three-tuple in this case:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s">&quot;before_execute&quot;</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">before_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">conn</span><span class="p">,</span> <span class="n">clauseelement</span><span class="p">,</span> <span class="n">multiparams</span><span class="p">,</span> <span class="n">params</span><span class="p">):</span>
    <span class="c"># do something with clauseelement, multiparams, params</span>
    <span class="k">return</span> <span class="n">clauseelement</span><span class="p">,</span> <span class="n">multiparams</span><span class="p">,</span> <span class="n">params</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>clauseelement</strong> &#8211; SQL expression construct, <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a>
instance, or string statement passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>.</li>
<li><strong>multiparams</strong> &#8211; Multiple parameter sets, a list of dictionaries.</li>
<li><strong>params</strong> &#8211; Single parameter set, a single dictionary.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>See also:</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_cursor_execute()</span></tt></a></p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.begin">
<tt class="descname">begin</tt><big>(</big><em>conn</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.begin" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.begin_twophase">
<tt class="descname">begin_twophase</tt><big>(</big><em>conn</em>, <em>xid</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.begin_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin_twophase() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>xid</strong> &#8211; two-phase XID identifier</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.commit">
<tt class="descname">commit</tt><big>(</big><em>conn</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.commit" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit() events, as initiated by a
<a class="reference internal" href="connections.html#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a>.</p>
<p>Note that the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> may also &#8220;auto-commit&#8221;
a DBAPI connection upon checkin, if the <tt class="docutils literal"><span class="pre">reset_on_return</span></tt>
flag is set to the value <tt class="docutils literal"><span class="pre">'commit'</span></tt>.  To intercept this
commit, use the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.reset()</span></tt></a> hook.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.commit_twophase">
<tt class="descname">commit_twophase</tt><big>(</big><em>conn</em>, <em>xid</em>, <em>is_prepared</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.commit_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit_twophase() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>xid</strong> &#8211; two-phase XID identifier</li>
<li><strong>is_prepared</strong> &#8211; boolean, indicates if
<a class="reference internal" href="connections.html#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.TwoPhaseTransaction.prepare"><tt class="xref py py-meth docutils literal"><span class="pre">TwoPhaseTransaction.prepare()</span></tt></a> was called.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.dbapi_error">
<tt class="descname">dbapi_error</tt><big>(</big><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>exception</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.dbapi_error" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept a raw DBAPI error.</p>
<p>This event is called with the DBAPI exception instance
received from the DBAPI itself, <em>before</em> SQLAlchemy wraps the
exception with it&#8217;s own exception wrappers, and before any
other operations are performed on the DBAPI cursor; the
existing transaction remains in effect as well as any state
on the cursor.</p>
<p>The use case here is to inject low-level exception handling
into an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, typically for logging and
debugging purposes.   In general, user code should <strong>not</strong> modify
any state or throw any exceptions here as this will
interfere with SQLAlchemy&#8217;s cleanup and error handling
routines.</p>
<p>Subsequent to this hook, SQLAlchemy may attempt any
number of operations on the connection/cursor, including
closing the cursor, rolling back of the transaction in the
case of connectionless execution, and disposing of the entire
connection pool if a &#8220;disconnect&#8221; was detected.   The
exception is then wrapped in a SQLAlchemy DBAPI exception
wrapper and re-thrown.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>cursor</strong> &#8211; DBAPI cursor object</li>
<li><strong>statement</strong> &#8211; string SQL statement</li>
<li><strong>parameters</strong> &#8211; Dictionary, tuple, or list of parameters being
passed to the <tt class="docutils literal"><span class="pre">execute()</span></tt> or <tt class="docutils literal"><span class="pre">executemany()</span></tt> method of the
DBAPI <tt class="docutils literal"><span class="pre">cursor</span></tt>.  In some cases may be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>context</strong> &#8211; <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> object in use.  May
be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>exception</strong> &#8211; The <strong>unwrapped</strong> exception emitted directly from the
DBAPI.  The class here is specific to the DBAPI module in use.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p class="versionadded">
<span class="versionmodified">New in version 0.7.7.</span></p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.prepare_twophase">
<tt class="descname">prepare_twophase</tt><big>(</big><em>conn</em>, <em>xid</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.prepare_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept prepare_twophase() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>xid</strong> &#8211; two-phase XID identifier</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.release_savepoint">
<tt class="descname">release_savepoint</tt><big>(</big><em>conn</em>, <em>name</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.release_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept release_savepoint() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>name</strong> &#8211; specified name used for the savepoint.</li>
<li><strong>context</strong> &#8211; <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> in use.  May be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback">
<tt class="descname">rollback</tt><big>(</big><em>conn</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback() events, as initiated by a
<a class="reference internal" href="connections.html#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a>.</p>
<p>Note that the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> also &#8220;auto-rolls back&#8221;
a DBAPI connection upon checkin, if the <tt class="docutils literal"><span class="pre">reset_on_return</span></tt>
flag is set to its default value of <tt class="docutils literal"><span class="pre">'rollback'</span></tt>.
To intercept this
rollback, use the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.reset()</span></tt></a> hook.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</td>
</tr>
</tbody>
</table>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.reset()</span></tt></a></p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback_savepoint">
<tt class="descname">rollback_savepoint</tt><big>(</big><em>conn</em>, <em>name</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_savepoint() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>name</strong> &#8211; specified name used for the savepoint.</li>
<li><strong>context</strong> &#8211; <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> in use.  May be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback_twophase">
<tt class="descname">rollback_twophase</tt><big>(</big><em>conn</em>, <em>xid</em>, <em>is_prepared</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_twophase() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>xid</strong> &#8211; two-phase XID identifier</li>
<li><strong>is_prepared</strong> &#8211; boolean, indicates if
<a class="reference internal" href="connections.html#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.TwoPhaseTransaction.prepare"><tt class="xref py py-meth docutils literal"><span class="pre">TwoPhaseTransaction.prepare()</span></tt></a> was called.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.savepoint">
<tt class="descname">savepoint</tt><big>(</big><em>conn</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept savepoint() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><strong>name</strong> &#8211; specified name used for the savepoint.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="schema-events">
<h2>Schema Events<a class="headerlink" href="#schema-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.DDLEvents">
<em class="property">class </em><tt class="descclassname">sqlalchemy.events.</tt><tt class="descname">DDLEvents</tt><a class="headerlink" href="#sqlalchemy.events.DDLEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Define event listeners for schema objects,
that is, <a class="reference internal" href="schema.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a> and <tt class="xref py py-class docutils literal"><span class="pre">SchemaEvent</span></tt>
subclasses, including <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>,
<a class="reference internal" href="schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>.</p>
<p><a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> and <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> support events
specifically regarding when CREATE and DROP
DDL is emitted to the database.</p>
<p>Attachment events are also provided to customize
behavior whenever a child schema element is associated
with a parent, such as, when a <a class="reference internal" href="schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> is associated
with its <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>, when a <a class="reference internal" href="schema.html#sqlalchemy.schema.ForeignKeyConstraint" title="sqlalchemy.schema.ForeignKeyConstraint"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKeyConstraint</span></tt></a>
is associated with a <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>, etc.</p>
<p>Example using the <tt class="docutils literal"><span class="pre">after_create</span></tt> event:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Table</span><span class="p">,</span> <span class="n">Column</span><span class="p">,</span> <span class="n">Metadata</span><span class="p">,</span> <span class="n">Integer</span>

<span class="n">m</span> <span class="o">=</span> <span class="n">MetaData</span><span class="p">()</span>
<span class="n">some_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;some_table&#39;</span><span class="p">,</span> <span class="n">m</span><span class="p">,</span> <span class="n">Column</span><span class="p">(</span><span class="s">&#39;data&#39;</span><span class="p">,</span> <span class="n">Integer</span><span class="p">))</span>

<span class="k">def</span> <span class="nf">after_create</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
    <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;ALTER TABLE </span><span class="si">%s</span><span class="s"> SET name=foo_</span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span>
                            <span class="p">(</span><span class="n">target</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">target</span><span class="o">.</span><span class="n">name</span><span class="p">))</span>

<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">some_table</span><span class="p">,</span> <span class="s">&quot;after_create&quot;</span><span class="p">,</span> <span class="n">after_create</span><span class="p">)</span></pre></div>
</div>
<p>DDL events integrate closely with the
<a class="reference internal" href="schema.html#sqlalchemy.schema.DDL" title="sqlalchemy.schema.DDL"><tt class="xref py py-class docutils literal"><span class="pre">DDL</span></tt></a> class and the <a class="reference internal" href="schema.html#sqlalchemy.schema.DDLElement" title="sqlalchemy.schema.DDLElement"><tt class="xref py py-class docutils literal"><span class="pre">DDLElement</span></tt></a> hierarchy
of DDL clause constructs, which are themselves appropriate
as listener callables:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">DDL</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
    <span class="n">some_table</span><span class="p">,</span>
    <span class="s">&quot;after_create&quot;</span><span class="p">,</span>
    <span class="n">DDL</span><span class="p">(</span><span class="s">&quot;ALTER TABLE </span><span class="si">%(table)s</span><span class="s"> SET name=foo_</span><span class="si">%(table)s</span><span class="s">&quot;</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The methods here define the name of an event as well
as the names of members that are passed to listener
functions.</p>
<p>See also:</p>
<blockquote>
<div><p><a class="reference internal" href="event.html"><em>Events</em></a></p>
<p><a class="reference internal" href="schema.html#sqlalchemy.schema.DDLElement" title="sqlalchemy.schema.DDLElement"><tt class="xref py py-class docutils literal"><span class="pre">DDLElement</span></tt></a></p>
<p><a class="reference internal" href="schema.html#sqlalchemy.schema.DDL" title="sqlalchemy.schema.DDL"><tt class="xref py py-class docutils literal"><span class="pre">DDL</span></tt></a></p>
<p><a class="reference internal" href="schema.html#schema-ddl-sequences"><em>Controlling DDL Sequences</em></a></p>
</div></blockquote>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_create">
<tt class="descname">after_create</tt><big>(</big><em>target</em>, <em>connection</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after CREATE statments are emitted.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>target</strong> &#8211; the <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> or <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>
object which is the target of the event.</li>
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> where the
CREATE statement or statements have been emitted.</li>
<li><strong>**kw</strong> &#8211; additional keyword arguments relevant
to the event.  The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_drop">
<tt class="descname">after_drop</tt><big>(</big><em>target</em>, <em>connection</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after DROP statments are emitted.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>target</strong> &#8211; the <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> or <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>
object which is the target of the event.</li>
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> where the
DROP statement or statements have been emitted.</li>
<li><strong>**kw</strong> &#8211; additional keyword arguments relevant
to the event.  The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_parent_attach">
<tt class="descname">after_parent_attach</tt><big>(</big><em>target</em>, <em>parent</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_parent_attach" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after a <a class="reference internal" href="schema.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a> is associated with
a parent <a class="reference internal" href="schema.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>target</strong> &#8211; the target object</li>
<li><strong>parent</strong> &#8211; the parent to which the target is being attached.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">event.listen()</span></tt></a> also accepts a modifier for this event:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>propagate=False</strong> &#8211; When True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="schema.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><tt class="xref py py-meth docutils literal"><span class="pre">Table.tometadata()</span></tt></a> is used.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_create">
<tt class="descname">before_create</tt><big>(</big><em>target</em>, <em>connection</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before CREATE statments are emitted.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>target</strong> &#8211; the <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> or <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>
object which is the target of the event.</li>
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> where the
CREATE statement or statements will be emitted.</li>
<li><strong>**kw</strong> &#8211; additional keyword arguments relevant
to the event.  The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_drop">
<tt class="descname">before_drop</tt><big>(</big><em>target</em>, <em>connection</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before DROP statments are emitted.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>target</strong> &#8211; the <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> or <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>
object which is the target of the event.</li>
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> where the
DROP statement or statements will be emitted.</li>
<li><strong>**kw</strong> &#8211; additional keyword arguments relevant
to the event.  The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_parent_attach">
<tt class="descname">before_parent_attach</tt><big>(</big><em>target</em>, <em>parent</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_parent_attach" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before a <a class="reference internal" href="schema.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a> is associated with
a parent <a class="reference internal" href="schema.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>target</strong> &#8211; the target object</li>
<li><strong>parent</strong> &#8211; the parent to which the target is being attached.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">event.listen()</span></tt></a> also accepts a modifier for this event:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>propagate=False</strong> &#8211; When True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="schema.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><tt class="xref py py-meth docutils literal"><span class="pre">Table.tometadata()</span></tt></a> is used.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.column_reflect">
<tt class="descname">column_reflect</tt><big>(</big><em>inspector</em>, <em>table</em>, <em>column_info</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.column_reflect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called for each unit of &#8216;column info&#8217; retrieved when
a <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> is being reflected.</p>
<p>The dictionary of column information as returned by the
dialect is passed, and can be modified.  The dictionary
is that returned in each element of the list returned
by <a class="reference internal" href="schema.html#sqlalchemy.engine.reflection.Inspector.get_columns" title="sqlalchemy.engine.reflection.Inspector.get_columns"><tt class="xref py py-meth docutils literal"><span class="pre">reflection.Inspector.get_columns()</span></tt></a>.</p>
<p>The event is called before any action is taken against
this dictionary, and the contents can be modified.
The <a class="reference internal" href="schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> specific arguments <tt class="docutils literal"><span class="pre">info</span></tt>, <tt class="docutils literal"><span class="pre">key</span></tt>,
and <tt class="docutils literal"><span class="pre">quote</span></tt> can also be added to the dictionary and
will be passed to the constructor of <a class="reference internal" href="schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>.</p>
<p>Note that this event is only meaningful if either
associated with the <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> class across the
board, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.schema</span> <span class="kn">import</span> <span class="n">Table</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>

<span class="k">def</span> <span class="nf">listen_for_reflect</span><span class="p">(</span><span class="n">inspector</span><span class="p">,</span> <span class="n">table</span><span class="p">,</span> <span class="n">column_info</span><span class="p">):</span>
    <span class="s">&quot;receive a column_reflect event&quot;</span>
    <span class="c"># ...</span>

<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
        <span class="n">Table</span><span class="p">,</span>
        <span class="s">&#39;column_reflect&#39;</span><span class="p">,</span>
        <span class="n">listen_for_reflect</span><span class="p">)</span></pre></div>
</div>
<p>...or with a specific <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> instance using
the <tt class="docutils literal"><span class="pre">listeners</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">listen_for_reflect</span><span class="p">(</span><span class="n">inspector</span><span class="p">,</span> <span class="n">table</span><span class="p">,</span> <span class="n">column_info</span><span class="p">):</span>
    <span class="s">&quot;receive a column_reflect event&quot;</span>
    <span class="c"># ...</span>

<span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span>
    <span class="s">&#39;sometable&#39;</span><span class="p">,</span>
    <span class="n">autoload</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
    <span class="n">listeners</span><span class="o">=</span><span class="p">[</span>
        <span class="p">(</span><span class="s">&#39;column_reflect&#39;</span><span class="p">,</span> <span class="n">listen_for_reflect</span><span class="p">)</span>
    <span class="p">])</span></pre></div>
</div>
<p>This because the reflection process initiated by <tt class="docutils literal"><span class="pre">autoload=True</span></tt>
completes within the scope of the constructor for <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.events.SchemaEventTarget">
<em class="property">class </em><tt class="descclassname">sqlalchemy.events.</tt><tt class="descname">SchemaEventTarget</tt><a class="headerlink" href="#sqlalchemy.events.SchemaEventTarget" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for elements that are the targets of <a class="reference internal" href="#sqlalchemy.events.DDLEvents" title="sqlalchemy.events.DDLEvents"><tt class="xref py py-class docutils literal"><span class="pre">DDLEvents</span></tt></a>
events.</p>
<p>This includes <a class="reference internal" href="schema.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a> as well as <a class="reference internal" href="types.html#sqlalchemy.types.SchemaType" title="sqlalchemy.types.SchemaType"><tt class="xref py py-class docutils literal"><span class="pre">SchemaType</span></tt></a>.</p>
</dd></dl>

</div>
</div>

    </div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
        Previous:
        <a href="event.html" title="previous chapter">Events</a>
        Next:
        <a href="compiler.html" title="next chapter">Custom SQL Constructs and Compilation Extension</a>

    <div id="docs-copyright">
        &copy; <a href="../copyright.html">Copyright</a> 2007-2013, the SQLAlchemy authors and contributors.
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
    </div>
</div>

</div>

        
    </body>
</html>


